import Doc from '~/components/layout/docs'
import Link from '~/components/text/link'
import Snippet from '~/components/snippet'
import { InlineCode } from '~/components/text/code'
import Caption from '~/components/text/caption'
import Card from '~/components/card'
import Note from '~/components/text/note'

export const meta = {
  title: 'Serverless Function Environment Variables and Secrets',
  description:
    'Learn how to use environment variables and secrets in your Serverless Functions for ZEIT Now deployments.',
  editUrl: 'pages/docs/v2/serverless-functions/env-and-secrets.mdx',
  lastEdited: '2020-01-08T22:17:44.000Z'
}

When using Serverless Functions, it may be necessary to use [environment variables](https://en.wikipedia.org/wiki/Environment_variable).

Adding environment variables requires two steps, defining the environment variable, then making it available to your Serverless Functions.

<Note>
  This section covers how to make environment variables available during{' '}
  <b>Run Time</b>, if you would like to make them available at <b>Build Time</b>,
  please see the <Link href="/docs/v2/build-step/#using-environment-variables-and-secrets">
    Build Step documentation
  </Link>.
</Note>

## Adding Secrets

To define an environment variable for a deployment, use **Now Secrets**. By using **Now Secrets**, the data will be encrypted and stored securely.

Adding **Now Secrets** can be done with [Now CLI](/download), which provides three options to work with them.

<Note>
  When adding Now Secrets with Now CLI, the secret name is automatically
  lowercased before being stored.
</Note>

To **define a Now Secret**, use the following command:

<Snippet dark text="now secrets add <secret-name> <secret-value>" />
<Caption>Defining a <b>Now Secret</b> using <Link href="/download">Now CLI</Link>.</Caption>

To **remove a Now Secret**, use the following command:

<Snippet dark text="now secrets rm <secret-name>" />
<Caption>Removing a <b>Now Secret</b> using <Link href="/download">Now CLI</Link>.</Caption>

To **rename a Now Secret**, use the following command:

<Snippet dark text="now secrets rename <secret-name> <new-name>" />
<Caption>Renaming a <b>Now Secret</b> using <Link href="/download">Now CLI</Link>.</Caption>

## Providing Environment Variables

To provide your Serverless Functions with the environment variables you have defined, whether declared in a `.env` file [during local development](#during-local-development) or as a [Now Secret](#adding-secrets), create a `now.json` file like the one below:

```json
{
  "env": {
    "VARIABLE_NAME": "@variable-name"
  }
}
```

<Caption>
  An example <InlineCode>now.json</InlineCode> file that provides Serverless
  Functions with a defined environment variable.
</Caption>

When providing environment variables to your application, the value should always be prefixed with `@`, followed by the name of the [Now Secret](#adding-secrets) or environment variable name if using an `.env` file [during local development](#during-local-development).

To use the environment variable from inside the application you would need to reference it using the correct syntax for the language being used. For example, using Node.js, the syntax would be:

```
process.env.VARIABLE_NAME
```

<Caption>
  Accessing a defined environment variable from within a Node.js application.
</Caption>

Now, whenever the `process.env.VARIABLE_NAME` key is used, it will provide the application with the value declared either by the [Now Secret](#adding-secrets) or [environment variable](#during-local-development), dependent on the environment the application is running in.

<Note>
  To use environment variables at the <b>build step of your application</b>,
  refer to the{' '}
  <Link href="/docs/v2/build-step/#using-environment-variables-and-secrets">
    build step documentation
  </Link>
  .
</Note>

## During Local Development

When using `now dev` to [develop your Serverless Functions locally](/docs/v2/serverless-functions/introduction/#local-development), [Now Secrets](#adding-secrets) are not available. This is a security measure, to prevent accidental use of production secrets during development.

To use environment variables during local development, create a `.env` file at the root of your project directory, for example:

```
VARIABLE_NAME=variable_value
```

<Caption>
  An example <InlineCode>.env</InlineCode> file that provides Serverless
  Functions with a defined environment variable.
</Caption>

<Note type="warning">
  Usage of a <InlineCode>.env</InlineCode> file is only possible during local
  development and will not be made available when deploying as a security
  measure.
</Note>

## Updating Environment Variables

Environment variables are made available to the runtime of Serverless Functions, meaning that they do not update in the application unless it is redeployed.

If you change the value of a [Now Secret](#adding-secrets) or environment variable and want your application to be aware of this, you should create a new deployment.

## Reserved Variables

The ZEIT Now platform reserves the usage of some environment variable names by default. You can find a list of these names in the [limits documentation](/docs/v2/platform/limits/#reserved-variables).

## Related

For more information on what to do next, we recommend the following articles:

<Card
  title="Supported Languages"
  href="/docs/v2/serverless-functions/supported-languages"
>
  Learn which languages you can use to build your Serverless Functions.
</Card>

export default ({ children }) => <Doc meta={meta}>{children}</Doc>

export const config = {
  amp: 'hybrid'
}
